home *** CD-ROM | disk | FTP | other *** search
/ TeX 1995 July / TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO / macros / lollipop / out.tex < prev    next >
Text File  |  1993-01-28  |  13KB  |  333 lines
  1. % Out.tex copyright 1992/3 Victor Eijkhout
  2. %
  3. \Chapter[chap:output] output
  4.  
  5. Every page is formatted according to a `page grid' consisting of
  6. three elements:
  7.  
  8. \Enumerate \item the page head, this is everything that's over the
  9. running text;
  10. \item the page foot, this is everything that is below the running
  11. text;
  12. \item the running text. \TeX\ acts as if text is on a long scroll,
  13. and the running text part of a page is simply a portion cut off from
  14. this scroll.\>
  15. Either or both of the head and foot of the page can be empty, but
  16. usually one of the two contains a page number.
  17.  
  18. \OutExample
  19. \OptionsMacro:ManPageSize=raggedbottom:10pt topskip:12pt
  20.  height:page=5cm width:page=6cm Stop
  21. \DefinePageGrid:TestPage macro:ManPageSize
  22.  pagerule textband:start text textband:stop
  23.  pagerule band:start PageCounter band:stop Stop
  24. \TestPage 
  25. This page does not contain much special.\EjectPage
  26. This page is hardly better.
  27. \OutExampleStop
  28.  
  29. This example illustrates how you first define a page grid by
  30. \refcs{DefinePageGrid}, and then activate it by calling its name. That
  31. last action is in fact not necessary: each definition of a page grid
  32. automatically installs that grid as the current one.
  33.  
  34. \Section Page dimensions
  35.  
  36. Most of the time it is easiest to specify the total height of a page,
  37. that is, including head and bottom, but sometimes it is more
  38. convenient to specify the height of the text, and let the head and
  39. foot simply go over and under that.
  40.  
  41. In the first case you can give the command \refcs{Height} with
  42. two parameters:
  43. \Ver>\Height:Page=23.5cm<Rev or inside a page grid definition the
  44. option \refopt{height}\n{:page=...}.
  45.  
  46. In the second case you can give the command
  47. \Ver>\Height:Text=19.55cm<Rev or inside a page grid definition the
  48. option \opt{height:text=...}.
  49.  
  50. In page grid definitions there is the additional option
  51. \opt{height:lines=23}.
  52.  
  53. The \cs{Height} command cannot be used in a page grid definition.
  54.  
  55. \Section Positioning the page on the paper
  56.  
  57. If your printer driver is up to specs (and you have not done any
  58. creative macro writing) it should have the upper left corner of the
  59. text landing at $2.54$cm from the top and left side of the paper.
  60. If the result is not to your liking, you can shift the page by
  61. \Ver>\Distance:hoffset= ...
  62. \Distance:voffset= ...<Rev
  63. These offset parameters are zero ordinarily, and they indicate the
  64. extra shift added to the customary $2.54$cm in horizontal and
  65. vertical direction.
  66.  
  67. \Section Page head, foot, text
  68.  
  69. Somewhere in the page grid the option \refopt{text} has to appear. This
  70. option has to be inside a \refopt{textband}:
  71. \Ver>    textband:start text textband:stop<Rev
  72. This is not a case of overspecification, because inside a textband
  73. the text option can appear more than once. In this manner a multicolumn
  74. page grid can be specified.
  75.  
  76. \def\sometext{Just a bit of words, words. }
  77. \edef\sometext{\sometext\sometext\sometext}
  78. \edef\sometext{\sometext\sometext\sometext\sometext}
  79. \OutExample
  80. \DefinePageGrid:TestPage macro:ManPageSize
  81.  pagerule textband:start text hwhite:10pt text textband:stop
  82.  pagerule band:start PageCounter band:stop Stop
  83. \FlushRight:no \sometext
  84. \OutExampleStop
  85.  
  86. Next to the option \opt{textband} there is \refopt{band}.
  87. Both are ways of
  88. creating a page wide band. The option \opt{band} is used for all
  89. material that is not a text column, for instance footers, as in the
  90. above examples.
  91.  
  92. The option \opt{band} can have one unusual parameter: \n{invisible}.
  93. This makes the band act as if it has zero height or width, depending
  94. on whether it is below or above the text, respectively.
  95.  
  96. \OutExample
  97. \DefinePageGrid:TestPage macro:ManPageSize
  98.  pagerule textband:start text hwhite:10pt text textband:stop
  99.  pagerule 
  100.  band:invisible block:start Style:bold PageCounter Spaces:2
  101.      stickout:left band:stop Stop
  102. \FlushRight:no \sometext
  103. \OutExampleStop
  104.  
  105. \SubSection More about text bands
  106.  
  107. The text band is that part of the page that has the text in it. You can
  108. also put other material in it, such as rules or white space.
  109.  
  110. \OutExample 
  111. \DefinePageGrid:TestPage macro:ManPageSize pagerule 
  112.  textband:start vrule white:3pt text white:3pt vrule textband:stop 
  113.  pagerule band:start white:fillup PageCounter band:stop Stop
  114. \TestPage This page contains some text, a bit more text,
  115. and even more than that. In all still just a few lines.\EjectPage
  116. This page contains more text, still more text, and still more. 
  117. \OutExampleStop
  118.  
  119. In the previous example the width of the page was specified.
  120. If we only give the width of the text, the page width is calculated
  121. dynamically. 
  122.  
  123. \OutExample 
  124. \DefinePageGrid:TestPage macro:ManPageSize
  125.  textband:start vrule white:3pt text white:3pt vrule textband:stop
  126.  pagerule band:start white:fillup PageCounter band:stop Stop
  127. \noindent This page contains some text, a bit more text,
  128. and even more than that. In all still just a few lines.\EjectPage
  129. This page contains more text, still more text, and still more. 
  130. \OutExampleStop
  131.  
  132. Note how the \refopt{pagerule} and \opt{band} objects stretch
  133. with the page.
  134.  
  135.  
  136. \SubSection Topskip
  137.  
  138. In between the page head and the text is some white space, the
  139. topskip, with special properties. The topskip is defined from the
  140. bottom of the head to the bottom of the first line of the text. If
  141. the height of this first line varies from page to page the topskip
  142. acts as a buffer, keeping the bottom-to-bottom distance constant.
  143.  
  144. Topskip is set by the option \refopt{topskip}, for example
  145. \Ver>    topskip:25pt<Rev
  146. but if this option is left out, the page grid uses the value of
  147. \cs{topskip} that was current at the time of the definition.
  148. Unfortunately there is no way to change this value after the definition.
  149.  
  150. \Section[sec:page-counter] The page number
  151.  
  152. The page number behaves as if it had been defined by
  153. \Ver>\NewCounter:Page
  154. \CounterRepresentation:Page=1<Rev
  155. Thus you can use any command from section~\ref[sec:counters] on it.
  156. For instance, you can have page numbers in roman numerals by 
  157. specifying
  158. \Ver>\CounterRepresentation:Page=I<Rev
  159.  
  160. The page number is typically used as the option \refopt{PageCounter},
  161. but for some applications the corresponding command \refcs{PageCounter}
  162. can be used.
  163.  
  164. If you process a \Lollipop\ document you see that everytime a page is
  165. generated, an item such as \ver>[8,7]> is written on the log file or the
  166. screen. Most of the time the two numbers will be the same, as in
  167. \ver>[8,8]>, but they will differ if you have tinkered with the page
  168. number. The first number is the `sheet counter': it counts how many
  169. pages you have produced so far. The second number is the value of
  170. \cs{PageCounter} for the page that was written out. Take a look at the
  171. log file for this manual for an example.
  172.  
  173. \Section[sec:page:tests] Page tests
  174.  
  175. The page grid definition can set/query several properties of the
  176. page. The following tests have been provided (see
  177. section~\ref[sec:tests] for tests):
  178. \Ver>\DefineTest:IsRightPage
  179. \DefineTest:IsLeftPage
  180. \DefineTest:FirstPage
  181. \DefineTest:LastPage
  182. \DefineTest:FlushBottom<Rev
  183. \Itemize\item The tests for left/right pages are done by
  184.  testing whether the page number of odd or even.
  185. \item The first/last page tests can be used either for the whole
  186. document, or for a file that's loaded as an \cs{InputFile}.
  187. \item The first page test doesn't work at present.
  188. \>
  189.  
  190. \OutExample
  191. \DefinePageGrid:TestPage macro:ManPageSize
  192.  pagerule textband:start text textband:stop pagerule
  193.  band:start ifIsLeftPage else hwhite:fillup fi PageCounter 
  194.      band:stop Stop \SetCounter:Page=12
  195. This is a left hand page. \EjectPage 
  196. This page is on the right side of a spread. 
  197. \OutExampleStop
  198.  
  199. \Section[sec:head/foot] Running heads / footers
  200.  
  201. Above it was explained how pages can be given a head and foot part.
  202. Quite often you want changing information in such parts, for instance
  203. the head of a left page often contains the number or title of section
  204. that was current when that page started; the head of a right page
  205. often contains the number or title of the section that was current
  206. when that page ended.
  207.  
  208. In \Lollipop\ all constructs that have a title or a counter can have
  209. that information referenced in page grids.
  210. \Description\item \refcs{FirstPlaced}:SectionTitle
  211. Take the title of the first section that started on this page, or
  212. the last one that started before this page if no section started on
  213. this page.\item \refcs{LastPlaced}:SubSectionCounter
  214. Take the title of the last subsection that started on this page, or
  215. the last one that started before this page if no subsection started
  216. on this pgae.\item \refcs{PreviousPlaced}:SectionCounter
  217. Take the counter value of the last section that started before this
  218. page.\>
  219.  
  220. \OutExample
  221. \DefinePageGrid:TestPage macro:ManPageSize
  222.  pagerule textband:start text textband:stop pagerule 
  223.  band:start Style:italic FirstPlaced:HeadTitle
  224.             white:fillup PageCounter band:stop Stop
  225. \DefineHeading:TestHeading Style:bold 
  226.  line:start TestHeadingCounter Spaces:2 title line:stop Stop
  227. \TestHeading A first section\par And some text.\EjectPage
  228. This page contains text. \TestHeading A second Section\par
  229. And more text.
  230. \OutExampleStop
  231.  
  232. The commands \cs{FirstPlaced} and \cs{PreviousPlaced} are typically
  233. used on left pages; \cs{LastPlaced} is more common on right pages.
  234. You can test on what sort of page you are; see
  235. section~\ref[sec:page:tests].
  236.  
  237. \OutExample
  238. \DefinePageGrid:TestPage macro:ManPageSize
  239.  pagerule textband:start text textband:stop pagerule 
  240.  band:start Style:italic 
  241.      ifIsLeftPage FirstPlaced:HeadTitle white:fillup fi
  242.      PageCounter
  243.      ifIsRightPage white:fillup LastPlaced:HeadTitle fi
  244.      band:stop Stop \SetCounter:Page=10
  245. \DefineHeading:TestHeading Style:bold 
  246.  line:start TestHeadingCounter Spaces:2 title line:stop Stop
  247. \TestHeading A first section\par And some text.
  248. \TestHeading Second section\par More text.\EjectPage
  249. \TestHeading Third section\par Is on the right page.
  250. \TestHeading Fourth section\par Concludes this page.
  251. \OutExampleStop
  252.  
  253.  
  254. \Section Alternating page grids
  255.  
  256. In \Lollipop\ it is very easy to switch page grids with the option
  257. \refopt{NextPageGrid}: you simply specify
  258.  \Ver>    NextPageGrid:otherpage<Rev as one of the options
  259. in the definition. If no next grid is indicated, the same page grid keeps
  260. being used continuously until another page grid is activated
  261. explicitly.
  262.  
  263. \OutExample
  264. \DefinePageGrid:LTestPage macro:ManPageSize
  265.  pagerule textband:start text textband:stop pagerule 
  266.  band:start Style:italic
  267.      PageCounter white:fillup FirstPlaced:HeadTitle   
  268.      band:stop NextPageGrid:RTestPage Stop
  269. \DefinePageGrid:RTestPage macro:ManPageSize
  270.  pagerule textband:start text textband:stop pagerule 
  271.  band:start Style:italic 
  272.      LastPlaced:HeadTitle white:fillup PageCounter
  273.      band:stop NextPageGrid:LTestPage Stop
  274. \SetCounter:Page=42
  275. \DefineHeading:TestHeading Style:bold 
  276.  line:start TestHeadingCounter Spaces:2 title line:stop Stop
  277. \LTestPage
  278. \TestHeading A first section\par And some text.
  279. \TestHeading Second section\par More text.\EjectPage
  280. \TestHeading Third section\par Is on the right page.
  281. \TestHeading Fourth section\par Concludes this page.
  282. \OutExampleStop
  283.  
  284. Another very useful application of this mechanism is to have a
  285. special definition for the opening page of a chapter. This manual uses a
  286. one-shot page grid \cs{EmptyPage} to remove the header and footer on the
  287. title page. It installs \cs{LeftPage} as the next grid.
  288.  
  289. \Section Additional User Control
  290.  
  291. \SubSection Elementary manipulation
  292.  
  293. There are a few commands for simple page manipulation:
  294. \Description\item \refcs{EjectPage}
  295. The current page is filled up with white space, and
  296. a new page is started.\item \refcs{ToRecto}
  297. As \cs{EjectPage} but if the next page is a left page (meaning
  298. that the page number is even) then the page number is increased by
  299. one, so that the next page is a right hand page.\item \refcs{ToVerso}
  300. As \cs{ToRecto}, except that the next page is a left page.
  301. \>
  302.  
  303. Additionally, \refcs{NoPages} lets
  304. all formatting and updating of values be performed, but
  305. no pages are written to the dvi file;
  306. \refcs{PagesOut}
  307. reverts the effect of previous command. Note that \cs{NoPages} does not
  308. incur any savings in time: full processing of the document is performed.
  309.  
  310. When a page is finished it rests in box \refcs{WholePage}. Then a call is
  311. made  to \refcs{CurrentShipout}, which is by default
  312. \ver>\shipout\box\WholePage>. However, you are free to define it
  313. otherwise. If your \cs{CurrentShipout} does not actually ship out pages,
  314. you may want to set \refcs{CountSheetsno} to prevent the effective page
  315. counter from being updated.
  316.  
  317. Redefining \cs{CurrentShipout} usually goes together with
  318. \refcs{SuspendOutput} and \refcs{ResumeOutput}. These commands
  319. temporarily save the page number and the current state of the page,
  320. including the current definition of \cs{CurrentOutput}. (This is necessary
  321. because a number of parameters concerned are changed by global
  322. assignments.) See the definition of \cs{OutputExample} in the appendix of
  323. this manual for an elaborate example. 
  324.  
  325. If you want to see te output routines in action, specify
  326. \Ver>\Trace:out<Rev In addition \Ver>\Trace:mark<Rev tells you what
  327. information is being saved for running head and foot lines.
  328.  
  329. \endinput
  330.  
  331. 92/11/20 Left right output examples
  332. 93/01/17 New description of \CurrentShipout
  333.